Creating a Format Object for a Page in a Document(IM:XP)

Inside Macintosh: QuickDraw GX Printing /: Chapter 3 - Page Formatting and Dialog Box Customization / Using Format Objects and Collection Items to Format Pages

Creating a Format Object for a Page in a Document
When a user wants to create a unique format or change its settings, the user chooses the Custom Page Setup menu item from the File menu. In response, you need to call the GXFormatDialog function to display the Custom Page Setup dialog box on the user's screen. Figure 3-12 shows the Custom Page Setup dialog box.
Figure 3-12 The Custom Page Setup dialog box

If the user clicks the More Choices button in the Custom Page Setup dialog box, QuickDraw GX expands the dialog box. Figure 3-13 shows the expanded Custom Page Setup dialog box.
Figure 3-13 The expanded Custom Page Setup dialog box[Missing image]

You need to create a new format object when a user chooses the Format button in the Custom Page Setup dialog box. For example, a user may create a four-page document, move to page 2, and then choose landscape orientation in the Custom Page Setup dialog box. The change to the page occurs when the user chooses the Format button.
Figure 3-14 shows a four-page document in which the second page uses a new format. Pages 1, 3, and 4 use the default format.
Figure 3-14 A four-page document in which page two uses a unique format object

Listing 3-9 shows how to create a new format object for a single page in a document. You should note that the GXNewFormat function sets the owner count for the new format object to 1.
Listing 3-9 Creating a format object for a page in a document
OSErr MyPageFormatDialog(MyDocumentPtr myDocument)
{
   OSErr             err = noErr;
   gxDialogResult    result;
   gxEditMenuRecord  editMenuRec;
   gxFormat          pageFormat;
   Boolean           newPgFormat = false;

/* Fill in the location of your application's Edit menu items. */
   editMenuRec.editMenuID  = mEdit;
   editMenuRec.cutItem     = kCut;
   editMenuRec.copyItem    = kCopy;
   editMenuRec.pasteItem   = kPaste;
   editMenuRec.clearItem   = kClear;
   editMenuRec.undoItem    = kUndo;
   
   /* Modify existing format object, else create a new one. */
   if (myDocument->pageFormat[myDocument->curPage -1] != nil)
      pageFormat = myDocument->pageFormat[myDocument->curPage -1];
   else
   {
      pageFormat = GXNewFormat(myDocument->documentJob);
      newPgFormat = true;
      err = GXGetJobError(myDocument->documentJob);
   }

   /* If no errors, display the Page Setup dialog box. */
   if (err == noErr)
   {
      result = GXFormatDialog(pageFormat, &editMenuRec, nil);

      /* 
         If the user chooses Remove, use the default format for
         this page. If the user chooses Format, store the new
         format with this page. If the user chooses Cancel,
         dispose of the cloned copy of the default format.
      */
      switch (result)
      {
         case gxRevertSelected:
            GXDisposeFormat(pageFormat);
            pageFormat = nil;

         case gxOKSelected:
            myDocument->pageFormat[myDocument->curPage -1] = 
                                                      pageFormat;

            /* 
               Place code here if your application needs to 
               adjust the document based on the new format object.
            */
            ...
            break;

         case gxCancelSelected:
            /* 
               If the user selects Cancel, dispose of the cloned
               copy of the default format object.
            */
            if (newPgFormat) GXDisposeFormat(pageFormat);
            break;
      }
   }
   return err;
}
Within the Custom Page Setup dialog box used to create unique formats, the user has the option to return to the default format by choosing the Remove button or to not save the format by choosing the Cancel button. These options are handled by the gxRevertSelected and gxCancelSelected cases, respectively, of the switch statement in Listing 3-9.
For example, if the user decides that the second page in a document should not have a unique format, the user may choose the Remove button in the Custom Page Setup dialog box. When the user chooses this button, your application needs to dispose of the format object for this page and reassociate it with the default format.
Although a user may choose to create a new format for a page using the Custom Page Setup dialog box, the user may also decide not to save this format.
For example, a user may click on page 4 of a document, choose the Custom Page Setup dialog box, and modify the scaling of this page. The user may then decide not to save the new scaling information and choose the Cancel button in the dialog box. When the user chooses the Cancel button, your application needs to dispose of the newly created format object and reassociate this page with its previously saved format object.
Saving a job object and the format objects it references is discussed in the chapter "Core Printing Features" in this book.